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1.0 Introduction 



1«0 Introduction 



The puroose of this standard Is to provide a meaningful set of 
practices which Mill lead to *good*> consistent* maintainable* 
organized an4 optimized SYHPL code. This document used the SYHPL 
Coding Standards DAP (DCS S1831)» the NQS COMPASS Programming 
Standard* and the SYMPl Coding Standards for the SYMPL project In 
SVL as guidelines. 

This standard Is In addition to the NOS COMPASS Programming 
Standard.! The procedures established In the COMPASS standard 
which are riot: uni que to the COMPASS language Cl.e. General 
Requirements* code Transmittal Rules* and Oayfile Messages) are 
to be adhered to for SYMPL programaing also. 

Where the word "must" appears In this standard* deviations 
will not be approved. Where the word "should" appears* reviewers 
may allow a deviation if the analyst can present convincing 
reasons for the deviation. 
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2.0 Coding Standards 



2.0 Codifig Standards 



2.1 General 



Ail declarations pertaining to a PROC or FUHC should use the 
folioHing grousing 

Formal Parameters 

XREFs 

OEFs 

STATUS names 

COMOECKs 

ITEMS 

BASED ARRAYS 

ARRAYS 

SWiTCHes 

Other 

All declarations or calls to COMOECKs should be In alphabetic 
order. 

Each declaration isust start on a separate line and must be 
accompanied by a comment describing Its function. 

Each executable stateaent «ust start on a separate line. 

Each BEGIN and END «ust be on a separate I Inc. 

A declaration which Is a one-bit field should be Boolean. 

Self "sodlfylng code must not be used. 

All labels begin in column one. Labels wust appear on lines 
by themselves except for embedded comments. All label names must 
be unique within a PROC/FUNC. 

TEST must never be used nI thout explicitly stating the 
induction variable It is testing. 

Define CONTROL DISJOINT and CONTROL INERT In a COMDECK. Use 
CONTROL OVERLAP and CONTROL REACTIVE to define the exceptions. 

Where numeric constants are established via DEFs or STATUS 
lists» the assumed nuneric values should not appear In the 
coding documentation. 

Items If i and K should be reserved as simple loop or control 
var labtes. 
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2*0 Coding Standards 
2*1 Genera! 



The code Ti us t not make assumptions about the octai representa- 
tion of characters. This representation varies between the 
various NOS character sets* 

Hachine Independent instructions when available should be used 
in preference to dependent structures* 



2*2 Parameters 



Use cat f-^»y-va^ ue parameters whenever possible. Only use 

cai l-by-addrass when the paraaeter Is modified within the 

procedure aid the new value of the parameters Is returned to the 
cai I Ing program* 

Reuse actual parameter lists whenever possible* If the 
parameters are used for a number of calls* use the same order of 
parameters for more efficient coding* 

Formal parameters must be declared within the PROC/FUHC rather 

than in a c3mwon deck* They can be ordered alphabetically or 
according to the calling sequence* 

An array item uust not be used as a parameter where a new 

value of the parameter is returned* since this feature is not 
supported In SfliPL. 



2*3 XREF 

Declaration of external procedure names are to be done in the 
following fornat. The referenced PROC/FUNC names are to be in 
alphabetic sequence* 

Examplet 



**♦* PROC Y - XREF LIST BEGIN, 
f 

XREF 
8E6m 

PROC APPLE J 
PROC BAMANAJ 
PROC ORANGE? 
END 



# 

♦*♦♦ 

# 



PROC Y - XREF LIST EHD. 



# PARES APPLE # 
» PEELS BANANA « 
« SQUEEZES ORANGE * 
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2.0 Coding Star^dards 
2.4 DEF 



2.4 DEF 



Use DEF to provl de symbol i c constants for numeric constants 
for ease In finding* identifying and modifying parameters. 

A DEF !BUst not be used to rename a variable. 

A DEF must not be used to redefine a function catt* a reserved 
>iord» or an ooeratlon unless it is used consistently throughout 
the system to improve clarity. OtherMlse* this may tend to 
obscure the actual code. All DEFs which redefine the code or 
make It a conditional compilation will be placed in a COMDECK. 

The DEF format for a full word octal constant Is in ^-dlglt 
parcels. For* example: 

DEF ERRMASK f. 0-0037 7740 0505 0000 7777*'#J i ERROR BIT MASK # 
2.5 STATUS 



Status fists should contain no unused posl tlons. Any unused 
positions must be filled with a dummy argument and have a 
i RESERVED i or i MOT USED f comaent. It may be better to use 
DEFs If there are many unused positions or any of the elements 
are expected to change. 

2.6 COMDECK 

Executable code should not be placed In a COMDECK. 

The declarations for a data structure must be wholly contained 
Mithln a single common deck. Where two or more data structures 
are i nterdeoendent* the declarations for the interdependent 
structures must be In the sane common deck. 

Logically associated data Items and structures should be 
declared in one COf^OECK unless they are only to be used by one 
module where they may be declared locally. 

One or more COMDECKs must contain al I decl ar at ions affecting 
table size which could be changed with the system. This Is to 
facilitate maintenance. 

Common decks must not be listed. 

A PRGM, pro: or FUNC should only call the common decks that It 
references. 
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2.0 Coding Standards 
2.6 COMOECK 



Every conmoti deck nust have an overview description of what It 
does* The following format Is to be used. The list control 
statements begin In column 48. 

# "deck name - description. # 

CONTROL NOLISTJ 
CONTROL IFEQ LISTCON,!? 
CONTROL LIST; 
CONTROL FIJ 

# 

*** deck name -description. 

* 

* (purpose) (several lines can be used) 

# 

CONTROL LIST; 

2.7 Non-array Items - 

The Items* the variable names* the types* the presets and the 
embedded comments should each be vertically aligned. Leave roon 
for ten character variable names and leave room for character 
counts on character type Items for ease of future maintenance. 

Variables sliould be declared al phabeti ca i i y. 

2.8 Arrays 

Arrays used by more than one PROC must be defined In 
CQ«D£CKs. 

Usage of Items from an array must always be subscripted. It 
Is confusing to default subscripts. 

Item declarations must be In ascending order (I.e. word bit 
to word n bit n). If overlapping declarations are used* then 
the item which spans other items must be first. 

Array Indices should start with zero. 

The array name* bounds and the allocation/size must be 
separated by blanks (e.g. ARRAY EXHAPLE COaOl P12)5 ). 

Items within an array are aligned with the begin for ease of 
reading. Each Item must be documented. 
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2.0 Coding Standards 
2.8 Arrays 



The Item nates* type/positions* preset values^ and embedded 
comnents should each be vertically aligned* Leave rooaj for ten 
character Itei names and for two digit ••ep"* "fblt** and "size" 
fields and use at least two spaces after the senlcolon to rase 
future maintenance*! 



2.9 FOR loops (Fast or Slow) 

FOR loops are of two types. In the slow FOR loop* the object 
code has a direct correspondence with the SYMPL statements. This 
Is not the case with fast loops* A f ast-f or-loop is optimized by 
pre-evaluating the STEP and UNTIL/WHILE elements. At least one 
cycle of the loop Is executed* 

Fast FOR loops and slow FOR loops must be used* A simple 
FOR statement inust not be used. For easi er readabi I I ty and 
prograamlng* use OFF statements to set up FASTFOR or SLOWFOR 
Instead of the CONTROL FASTLQOP or CONTROL SLOMLOOP. These OEF 
statements shojJd be placed In a CCMDECK. 

OEF FASTFOR iCONTRDL FASTLOOPj FOR# 
DEF SLOWFOR fCONTROL SLOWLOOPj FOR# 

For better optlnlzatlon consider using STEP/WHILE as an 
alternative to STEP/UNTIL* 

The induction variable must not be changed during the loop or 
by a FUHC called while evaluating the STEP/UNTIL/WHILE part* 

The exit fro» a loop should be through an UNTIL/WHILE or a 
return statement. The entry Into a loop must not be In the 
middle of the loop.' 

The executable statement(s) after the DO part of a FOR loop 
must be enclosed in a BEGIM/END pair. 

2.10 GOTQs and SWITCHes {Case Statementi 

60T0 should be employed only if the resulting source code is 
demonstrably superior In performance* clarity* maintainability* 
or extendlblfl ty. In spite of structured programming* 60T0s may 
make the code more efficient If employed properly. GOTOs may 
make It difficult to follow logic. Jumps Into FOR loops must not 
be used* Ju«ps Into code within a THEN or ELSE should not be 
used. Jumps backwards in the code should not be used* 
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2.0 Coding Staridards 

2.10 GOTOs and SWITCHes (Case Statement) 

A GOTO statement specifying a subscripted switch list way be 
used to sli«ulats a case stateraent. Each case should end with a 
GOTO branching to a common exlt» a RETURN stateaent* or an ABORT 
call* 

Simulated case statements «ay' use a nultlpliclty of labels 
for exits^ proyided that the selection of exit points is done 
to achieve consol fdatlon of similar sequences of code> and that 
all such labels are grouped together* See the Examples section 
for an example of a simulated case statement. 



2.11 IF 

The THEM and ELSE part of an IF statement must always use a 
BEGIN/END oalr.f If embedded comments are needed to describe the 
condition* they should be placed with either the THEN/ELSE or the 
associated 8EGI!4/EHD pair rather than on the IF. A stand alone 
comment following the THEN or EtSE may be used instead If 
embedded co««ents would be too long or would restrict the 
readability of the code. 

Related IF statements should not be nested more than 3 deep. 
A simulated ease statement may be used. 

Compound condl tl onals on an IF statement should be ordered 
such that the first condition Is the one which will most likely 
terminate the condition evaluation. 



2.12 Bead 

Avoid usifig bead functions unless necessary. Instead* the use 
of an array with partial-word I terns is preferred. Bead functions 
are difficult to update in a program if the data item that Is 
beaded Is ever changed. If used* do not cross-type (bit 
functions should be used only on numeric data* byte functions 
only on characters). 

Bead funstlons may be used to simulate data definition 
features not currently implemented with SYHPL such as repeating 
groups within a word. 
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2.0 Coding Standards 

2.13 PROCs» FO^Cs* and PRSHs 

2.13 PROCs» FWCs> and PRGHs 

XDEFs* atternate entry points* and Internal PROCs should not 
be used, they are hard to locate In the prograra and will make 
debugging ani modification more drffjcult. 

PROCs and FUNCs aust ha»e a fixed (not variable) number of 
parameters. 

The F option on the SYMPL cowwand must not be used. Instead* 
use CONTROL FTM In the source when needed. 
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3.0 Naming Cdnventlons 
3.0 Naming Conventions 



All declarations and PRQC/FUNC names should be descriptive. 

Routines -way use simple local variables named TMPl* TMP2» 
etc. However* such names can be used only for multi-purpose 
Items. Itaiis vilth a specific computational purpose should have 
a meaningful naie. 

All external Identifiers (PRGM* PROC» FUNC nawes) must be 7 or 
less characters. The loader truncates a naae to 7 characters. 

All Internal Identifiers C dec laratlons* arrays* status list 
names) must be 10 or less characters. A $ may be used as another 
letter In the alphabet. However* $ Is Invalid In the deck name 
because of MODIFY. 

All array Itesis should be prefixed by the first 3 or^ 
characters of the array name. The last 6 or 7 characters of the 
array item ar*e the descriptive name. 

All related OEFs should use the same prefix. 

Ait C0?1DSC!< names should be 7 characters In length and should 
be in the f ol IsmiI ng f orm 



COMxaaa 

where 



aaa » Symbolic name of COKDECK 

X » One of the CQMDECK indicators: 

A « COttOECKs used by more than one of the 
E# U> or Z SY«PL groups 

B « Data manager 

C * CPU code 

D « Display driver code 

£ « EXEC portion of MSS CSYMPLI 

F » Full screen editor CFSE) 

I * Initialization 

K « Transaction subsystem 

M « Mass storage error equivalents 

P » PP code 

S « Subsystem text symbols* constants 

T * Tables 

U « UtI I Itles (SYMPL) 

Z « Driver portion of MSS tSYMPLJ 
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4*0 Code ReadabI t ity 



4.0 Code Readability 



4*1 Format of Statements - 

AH dec! ar'atf ons must begin In column 7 and be finished before 
column 72. Column 72 must be blank to separate SYMPL code and 
comfflents fro^ MODIFY sequence numbers. Each line of Indentation 
is two spaces. 

Each 8ESrN/5M9 Is on a separate line. The first BEGIN Is In 
column 7. Subsequent BEGINs are each Indented two spaces. Code 
fol lowing th9 BEGIN* up to and including the next END* has the 
same indentation as the BEGIN unless exempted by some other rule 
(I.e. labels are In column 1). The END statement reduces the 
following Udentatlon by two spaces. Any BEGIN/END pair that 
brackets more than ten statements should have matching embedded 
comments on the BEGIN and END. Redundant BEGIN/END pairs should 
not be used to highlight module structure. This function Is 
better accomolished with, stand alone comments. 

Each THEM/ELSE/OO is on a separate line and Is placed directly 
beneath the IF or FOR portion of the statement. 

A statemer^t which overflows the line must Indent 2 spaces from 
the original state-»ent. 

Compound conditionals In an IF statement must be separated at 
the OR/AND If the entire statement does not fit on a single 
line. If the statement needs to be separated because of Its 
length or at the programmer-s option* then the ANO/OR plus Its 
condition needs a separate line and Is Indented two spaces. 

Examples 

IF C 

OR (A AMD B) 
THEN 

BEGIN 



F B 
OR C 
OR D 

HEN 
BEGIN 


IF B OR C OR D 
THEN 
BEGIN 

• 
• 


• 


• 


END 


• 
END 



END 

The format of the FOR statement fol lows the IF. If the entire 
statement will not fit on a single line* then the statement must 
be separated Into two lines and Indented two spaces. 
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4.0 Code ReadabI I fty 

4.1 For«at of Statements 



FASTFOR I«l STEP 1 

UNTIL 7 
DO 

8€SIM 



END 



4.2 Column 1 



The foltowlTg Items aust begin In column IJ 
Labels 

PRGH/P«!CJC/FUHC statements 
Slntjle llf^e comments 
Stand alone comsents 



4.3 Bl ank Lifjes 



A blank line nust be used In the foiioMing casess 

As the first line in each co«won deck 

Between all declaration groupings 

Before and after every stand-alone comi»ent 

Before and after all groups of conditional code 

Cexeeot COHDECK list control) 
After every END statement 
Before every label (or sequence of labels) 

Blank Unas (In addition to those required) may be 
used to Imprave the readability of the code. 

4.4 Page Ejects 



A page eject must be used as a separator between the 
declaration iroups and the body of code. 

If the declaration groups and the body of code Mill fit 
on a single page* five blank lines may be used rather than 
a page eject. I 
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5.0 Oocusientatlon Standards 



All docuaefitation «ust conform to the NOS operatin«3 system 
requirements,! This Includes rules concerning complete sentences* 
capitalization. punctuation, abr^jvlatlons, etc. All stand-alone 
cofflwents are conplete English sentences with correct punctuation, 
ending with a period. 

5.1 Comment Fonnats and Types 

Comments can appear In three different fonaatsx stand alone, 
single line and embedded. Stand a lone, cosuaents have four types 
determined by the nuieber of asterisks on the Initial line o^ a 
sequence of lines with asterisks In column 1. These four tyoes 
are recognized by the OOCHENT utility and cause some comments Cor 
codeJ to be Included In DOCMENT output depending on OOCMENT run 
time parameters. 



5.1.1 Embedded comments 

Embedded comments appear on the same line following a 
declaration or executable statement. The left delimiter must be 
preceded by at least two spaces and followed by only one soace. 
At least one soace follows the co»raent text before the right 
delimiter. At feast one space must follow the right dellmit»r. 
Column positioning rules for the left delimiter are given In the 
section "Documentation with Embedded Comments", 

5,1,2 Single Line Comments 

These comments have a left comment delimiter In column 1, the 
text starting In column 3 for title lines or In column 7 for 
common deck headers, and a right comment delimiter proceeded by 
at least one space all on a single line. This comment form Is 
used In the following cases* 
— Title I Ines 

— • Common deck headers 
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5.1.3 Stand Alone Coaaents 
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5*1*3 Stand Afone Comnents 



These co«i»ents consist of at least 5 lines with the first and 

last being blank lines* the secondhand next to last having (only) 

a co««ent delimiter In column 1 with the comment body starting 

with line 3. Each line of the comment body has an asterisk In 
column 1 Mith blanks normally found in columns 2-6* 

The Initial line of the comment body C I i ne 3) may have 1* 2» 3 

or 4 asterisks starting In column 1 depending on the type of 
output desired from the DOCMENT utility. 

5.1 .S.! Bracicets (♦**♦) 




The comment body consists of asterisks In columns 1-4 with 
text on the rest of the first line. The comment text should 
clearly indicate Mhich is the opening bracket and Mhich is the 
closing bracket. 

5.1.3.2 External Coflments <*♦♦) 



A comment body which is to be included In any DOCMENT run 
(external or Internal) has 3 asterisks In columns 1-3 of the 
first line of the comment body. The 3 asterisk form Is generally 
used to explaH the Interface to a SYMPL PRGH. It is also used 
In the header documentation for common decks. 



5.1.3.3 Internal Comments {*♦) 



A comment body which Is to be included in a OOCHENT run 
selecting Internal documentation in addition to external 
documentation has asterisks In columns 1 and 2 of the first line 
of the comment body. This is generally used to describe the 
interface far each PROC/FUNC. It may also be used to describe 
other important Information about a PROC/FUNC/PRGM. 



5-3 
NOS SYMPL CODI^IS STANDARD 

06/01/83 



5*0 Docuaiantati on Standards 
5«1«3«4 Modufie Comnents C*) 

5«1«3«4 Module CoMwents (♦) 

A cowuent body which is not to be Included in a DOCMENT run 
simply has 1 asterisk on the first line of the cowment body. 
This type of stand alone cowmen t is generally used to document 
design Information xhich helps one maintain or code revieM a 
module* 

This type of comment can present design information for the 
entire PRQC/FUNC» or for a sequence of code* It should answer 
the question* "how does this PRQC/FOHC code segment work?" 

5*2 Program LTevel Documentation 

Every PRG1 iiust have an overview describing what it does and 
external documentation describing how It is used. The overview 
documentation is very general, A description of the fields Is In 
the NOS coding standards* 

# 

♦** (heading) 

* ■ 

* Cpurposel 

♦ 

* (command format) 
* 

* PRGM program name. 

* ENTRY. ^ ..*.. 
* 

* EXIT. ,, ,,, 

* HESSASES.f ..... 

* NOTES. ..... 

* C0PYRI3HT CONTROL DATA CORPORATION, 1983. 
* 

In addition* a PRGM may have Internal and module comments as 
appropriate. 
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5.0 Documentation Standards 

5,3 Documentation of PROCs and FUNCs 



5.3 Oocunentatlon of PROCs and FUHCs 

Every PROC'/FUHC needs an Internal documentation section. It 
should answer the question: "hoti Is this PROC/FUNC used?*». The 
description of the different fields is In the NOS Coding 
Standards* 

# 

** C heading) 

* (purpose) 
* 

* (PROC or FUNC statement ulth semicolon omitted) 

* ENTRY ..••. 

* EXIT ..... 

* MESSAGES ..... 

* ^ ■ . " ■ 

* NOTES .."... 

* 

If a PROC or FU^C references a based array whose pointer Is In 
a common block* and the PROC or FUNC assumes that the pointer for 
that array Is set before the PROC or FUNC is called* the entry 
condition cotmants should state that assumption. 

In addition* a PROC/FUNC may have additional Internal comments 
and module comnents as appropriate. 

Where a higher level of documentation Is needed for a related 
group of PROCs an extra PROC should be added to contain the 
unifying documentation. 

5.4 Documentation with Embedded Comments 

Embedded comments are of two documentation forms (i.e. data 
declaraction or* action code). This Is the only type of a comment 
that need not be a complete sentence. This type of comment 
should not be continued onto another line. If absolutely 
necessary* t*ie comment may be continued on the following line. 
In this case the second line must not contain code. 

THEN # comment which is too long 

continuation of commment # 
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5.0 Oocunentation Standards 

5»4«1 Data Declaration Eabedded Comments 



5.4.1 Data Declaration Embedded Comments 



Every array* Item, status Item* DEF and 
documented with appropriate information. Each 
appear on a separate line accompanied by 
describing Its function {optionally* If this 
arrayj» It !»ay be bracketed by comment lines «lth 
columns 1 through 4 so that DOCHENT Mill process It. 



XREF i tern must be 

declaration should 

embedded comments 

Is an Important 

asterisks In 



Presets 
function of 



shauld be 
the preset* 



commented individuaiiy to reflect the 



The left delimiter of the embedded comment should 
38 unless the statement extends beyond column 35* in 
the dellislter is placed at least two spaces to the 
statement. 



be In column 

which case 

right of the 



5«4«2 Action Code Embedded Comments 



For BSGIN and EMD statements* the embedded comments are placed 
two spaces to the right of the statement. For other statements 
the embedded comments begin In column 38 unless the statement 
extends beyond column 35 In which case the delimiter is placed at 
least two spaces to the right of the statement. 



5.5 General Documentation for PRDCs* PRGMs or FUNCs 



Each PR6H, PROC» FUNC 
statement fol lowed by the 
that same line. SYMPL 
pseudo-ops must apoear as 
or FUNC, 



statement must have a corresponding END 

PRGH» PRCC* FUNC name as a comment on 

comments containing COHPASS-IIke title 

the second line in a SYMPL PRGM» PROC 



PRGM 0K5 

# TITLE aK - description of PRGM OK, 

BESIM f 0< f 



END i 0< # 



6-1 
NQS SYMPL CODTSG STANDARD 

06/01/83 



6*0 Examples 
6*0 Exaffiples 



6.1 COMDECK Examples 

17 38 48 71 

COMASPC 
CQMHON 

# COMASPC - STEP POINT CONTRCL. t 

CONTROL NOLISTJ 

CONTROL IFEQ LISTCQN#1| 

CONTROL LIST? 

CONTROL Fl; 
8ESIM i COMASPC i 

f 

*♦♦ COMASPC" - STEP POINT CONTROL. 

* 

♦ *COMASPC* CONTAINS DECLARATIONS USED J=OR CONTROL OF STEP MODE. 

OEF STEPC^T #*#J # NUMBER OF STEP POINTS - 1 # 

DEF STEPPNT (I) #B<{ I) * 1>STEPMASK#; # STEP POINT f 

STATUS STEPVAL # STEP POINT VALUES # 

51, # STAGING STEP POINT 1 # 

52, # STAGING STEP POINT 2 # 

53, # STAGING STEP POINT 3 # 
01* # DESTAGING STEP POINT 1 i 
021 # DESTAGING STEP POINT 2 i 

COMMQM ASPCCOM; 

BE6IS f ASPCCOM # 

ITEM HPMASK UJ # HALTED PROCESS MASK # 

ITEM STEPMASK Uj # STEP POINT MASK # 

rtRRAr ^PT rOJSTEPCNTl PCI); # HALTED PROCESS TABLE i 

ITEM HPTtLINK U<00»42,18); # HALTED PROCESS CHAIN LINK « 

END 

END « ASPCCOM # 
END # C3MASPC # 

CONTROL LIST; 
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6*0 Exanpfes 
6.2 PROC Exa«Pl e 

6.2 PROC Exanple 

1 7 ^_^_ ^ ^_ 

PROC PSFIHf CiO\rALUE1»CSPVALUE))} 

« TITLE PSFIM -INITIALIZES THE C0HFI6URARTIQH. 

BEGIN f PSFIN i 

*♦ PSFIN - INITIALIZES THE CONFIGURATION. 

* *PSFIN* INITIALIZES THE CONFIGURATION OF A FAMILY OF 

* DEVICES. 

* PROC PSFINICNOVALUEJWSPVALUE)) 

* ENTRY CNOVALUE) = NUMBER OF DEVICES IN A FAMILY. 
« CSPVALUE) » SPACE ASSIGNED TO EACH DEVICE. 

* ARRAY HEADER » PSEUDO PFC. 

* EXIT CONFIGURATION IS INITIALIZED. 

* NOTES THE SPECIFIED VALUES ARE PLACED IN THE HEADER. 

T-rcM MiVAfUE Ui # NUMBER OF DEVICES # 

ITEM sJvJlUE U5 * SPACE AVAILABLE PER DEVICE * 

# 

***♦ PROC PSFIN - XREF LIST BEGIN. 

i 

XREF 

PROrPSLOCK? i INTERLOCKS THE PSEUDO PFC i 

PROC PSUNLCKI t RETURNS THE PSEUDO PFC # 

END 

# 

♦*♦* PROC PSFIN - XREF LIST END. 

# 



+ 

# 
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DEF OFP*SeT f4ij 

OEF LISTCONf OiJ 
♦CALL COMAHSS 
♦CALL C0MZHE3 
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# DEVICE ENTRY OFFSET IN PFC f 



,; (( 



# 

* 
f 



ITEM I 
ITEM HUM 



IJ 
Ui 



i DO NOT LIST COMDECKS f 



# LOOP VARIABLE # 

# CALCULATED NUMBER # 

CONTROL EJECT? 



PSLOCKC HEADER) J 

SET VALUES IN THE HEADER, 



HEAD$M5r31 » NOVALUEj 

HEAD$SP0EVC03 » SPVALUEl 

NU1 « ^0\/ALUE ♦ SPVALUEJ 

HEADSSPFAMCOr » NUM| 

HEAOtSPAVFCOr « NUHj 

SLOWFO^ I « 1 STEP 1 UNTIL NDVALUE 

°°or^^u * SET SPACE AVAILAL8E # 

HEADSXXtl ♦ OFFSET] » SP VALUE J 
END 

PSUNLC<(HEADER)5 

RETURN? 

END i PSFIN f 



TERM 
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6«0 Exanptes 

6.3 Stati»s List/Status Switch Example 



6*3 Status List/Status Switch Example 



STATUS EUSTAT 
ERRORNO, 

ERRORFE* 
ERRORFi> 
ERRO?Hii» 



ITEM FLAS SIERSTATJ 

SWITCH ERRCASEIERSTAT 

OKJERRORNO* 

PFSXISTSJERRORFE* 

NQEMTRYiERRQRFM* 

WRITERRSERR0RNW5 



# ERROR STATUS # 
» NO ERROR # 

# FILE ALREADY EXISTS f 

# FILE HOT FOUND i 

# UNABLE TO WRITE RFC » 

# END OF *ERSTAT* * 

# ERROR CONDITION # 

» ERROR LIST # 
f NO ERROR # 

# FILE ALREADY EXISTS # 

# FILE QNT FOUND # 

# UNABLE TO WRITE RFC # 



A status list way also be defined with an upper Unit entry 
put at the end of the I 1st, ThI s upper limit can be used In 
the code to test that a variable Is within Its defined range. 
In this styfie the upper Halt entry Is terminated with a 
a seffli-colon on the same line. 



Example: 



STATUS Sf? STAT 
ERRO?N0> 
ERRORFS, 
ERRO?F>}> 
ERRORNWf 
SRR0?F»I0J 



♦ERROR STATUS # 

# NO ERROR # 

# FILE ALREADY EXISTS i 

# FILE NOT FOUND f 

» UNABLE TO WRITE RFC f 
i END OF *£RSTAT* # 
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6.3 Status List/Status Snitch Example 



* . 

* PROCESS THE ERROR RESPONSE. 

GOTO E^RCASEtFLAGl; 

i - 

* stand alar^e comment here or an embedded comment on the label. 
# 

PFEXISTSt i embedded comment * 



GOTO emo:ase; 

NOENTRYJ 



# embedded comment # 



GOTO e^o:asej 

WRITERRJ 



# embedded comment # 



GOTO EMOCASEJ 
0K» 

GOTO S^OCASEJ 
ENOCASEs 



# embedded comment f 



* PROCESS THE ERROR RESPONSE. 
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This addsndua describes changes to the NOS SYMPt coding 
standard for the Screen Management Facility <SMF> project. 
Certain oarts of this change In the standard shall be relevent 
only to the Full Screen Editor and not to the screen formatter* 

1. Structural changes _ . 

a. Nested procedures/functions are allowable under the 
following conditions. The terminology used here shall be 
"cofflpllation unit" for an outerpost PRGM/PROC/FUNC# since 
that Is the scope of the «ap and cross-reference In the 
listing. 

Procedures and functions may be nested. A compilation unit 
«ay contain XOEF-ed Internal routines provided that a 
PROC/FUNC coispl I atlon unit Is never called via the main entry 
point. Any routine may contain Internal routines which are 
not XOEF-ed. That Is* nesting of XDEF-ed PROCs Is only 
allowed one level deep. 

The second level of nesting Is used only for routines which 
perform an algorlthw not expected to be of value outside of 
the parent routine. Second' level nested routines should be 
very simple In their logical structure. The sane principles 
Mill apply for deeper level roiitfnes. 

Non-XOEF Internal procedures must have the same header 
documentation as any external procedure. 

b. External symbols may be more than 7 characters long. The 
programwer Is responsible to assure uniqueness within the 
first 7 characters. These oversize external names* while 
perwisslbia* are discouraged and should be used only when the 
prdgrawiner cannot reduce the routine name to a 7 character 
name wltJt sufficient clarity. 

c* COMPASS subroutines are allowed for optimization of tight 
loops. Such routines should be designed to contain a minimum 
of decision-making logic. 
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d. Each comjillatlon unit In the editor shall call COMAFSP as ? 
: f, IL? °'*""*" ^^^^* ^^'5 deck contains symbol and macro r.^£, - 
definitions which aust appear early In the source code. OtHerf*i.* 
coflsjBon decKs way be cal led e I ther In alphabetic order or In* vsn 
functional order. One example of functional order would be 
the storage mapping of a co««on block which can only be ' 
described by using several comiBon decks Cthis can arise In a 
situation where nested coanon decks would be desired but the 
product Is Is built via MODIFY) correct storage wapping would 
thus require that the co««on decks be called In a particular ^ 
order for which alphabetic naming may not be reasonable, v 

2« Statement formats , 

a. The FOR keyword may be used. CONTRDL FASTLOOP CFASTFOR) 
IS not psmltted. 

b, FOR loops and simulated case statements are al I owed to 
terminate with a RETURN statement or the lORET macro. In th» 
editor, the ERRJUMP call may be used to terminate any block 
of code. ERRJUHP will be a procedure which |s Itself allowed 

to execut* a Jump Into a procedure. ERRJUMP is used to clear = 
the editor Into a nominal condition after encountering a 
syntax error. In the edi tor, code may also be terminated by.. 
a call to a fatal-error routine. 

Loops may be based on labels and SOTO-s In place of FOR only 
when the programmer can defend this usage as substantially ' 
more efficient or as being simpler to maintain than 
functionally equivalent structured code. 1 



Simulated case statements may use a backward Jump to achlejv^t 
the common exit when the case Is embedded In an Iterative 
structure for which labels and SOTO-s are allowed. 



i 
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c. 4 PROC/PUNC/PRSH statement shall begin In column 1 for a 
co«pllatfor» unit and for a first-level nested PROC/FUMC. 
PRQjCi^PUNC statements nested to deeper levels shall be 
indented 2 columns per level* The body of code In a routine 
shall be Indented 2 columns from the PROC/FUNC statement. 
Code contained In a CONTROL IF bracket shall be indented 2 
columns from the CONTROL statement. BEGINS and ENDs shall be 
Indented 2 columns^ and the code within the BEGIN/END shall 
be aligned with the BEGIN/END. In the editor, IQBEGIN and 
lOENO macros shall be indented as though they are BE6IN/EM0. 



3. Documentation 

a. Oocunentaton of ENTRY/EXIT conditions and of storage 
usage must Include assumptions regarding manipulations of 
pointer siords for based arrays. 

b. For oonpllatlon units whose main entry point is uncalled, 
the main e^try may carry documentation considered applicable 
to all embedded procedures. 

c. XREF and XOEF may be provided byilsts of routine names 
In commoi decks. Such; lists of XDEF should be listed, but 
such lists of XREF should not be listed/except for a comment 
noting the call to the common deck. OOCHENT brackets are not 
required.* 

d. StantJ alone comments may be a single line starting with 
a pound sign In column 1 and ending with a pound sign In 
column 71, rather than the COMPASS style comment (asterisk In 
column 1 of the comment body). 

The use of preceeding and proceeding blank lines Is 
negotiable between the programmer and reviewer to achieve a 
mutually satisfactory visual effeft. Note that this 
simplified form for stand alone comments Is .only applicable 
for comments not intended to be printed by the OOCMENT 
utility. 

4. Pseudo-ree^trancy considerations (for FSE and SMFEX only). 

a. The SHFEX Executive may contain a limited number of 
labels within If or for blocks, and external labels within 
procedures* as necessary to Implement pseudo-reentrancy. 

b. SMFEX and FSE wl I 1 contain procedures subject to reentry 
under control of the SMFEX Executive. A reentrant procedure 
Is a procedure which calls another reentrant procedure or 
uses the delay or recall statements. There cannot be 
reentrant functions* 
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c« The r'eentrancy technique sever ly restricts the tfsage of 
local storage and of pair ameters. The programmer should 
dedicate coiRiRon block storage to the functions performed by ' '^ 
a reentrant routine* in preference to locals. Note that the ' 
coamon block Includes one general purpoise variable which Is 
stackable* so that reentrant routines can dynamically «■ 
allocate storage on a I Imi ted scale. ' ' 

d. Reentrant procedures must minimize the use of locat ^^ 
storage. Any sequence of code In a reentrant procedure which • 
uses focal storage must be preceded and followed by stand 
alone conments of the form 

# tasAi: f 

f mo- LOCAL # s 

The code within the comments cannot call any reentrant 
routlnes.l 

e. Reentrant procedures must minimize the use of parameters. 
When parameters are used. It Is essential that the parameters 
be read-only fi.e. the subroutine does not compute a new 
value)'j and fchey must be used before any feentraht procedure 
is called. Use of parameters shall be fdllotied by a stand 
alone coiment of the form* 

# EMD PARAMETERS i r ^ i 

f. Reentrant routines loise control by calling DELAY or 
RECALL.' In the single-user version, these are COMPASS^ 
subroutines which execute^ecail macros. In the multi-user 
version, these are D£F-ed to be calls into certain entry 
points within SMFEX to Invoke the multi-tasking executive. 

g. Reentrant routines are bracketed by the lOBEGIN and IOEHD ' 
macros. In the single-user version, these are DEF-ed ttj 
simply yield BEGIN and END. In the multi-user version, thes^' 
are OEF-ed to generate code to maintain data structures which 
help the S^^FEX multi-task executive supervise the reentry. 
Reentrant routines cannot use the RETURN statement, but can 
use the lORET macro. 



Al-5 
NOS SYHPL CODING STANDARD 

06/01/83 

Al.O Addendua for SMF Project 

h« Reentrant routines must be restricted as to the type of 
■onitor calls they can issue either explicitiy or by calling 
other routines.' In particular^ reentrant code aust use only 
CIO and each CIO call must be explicit. This effectively 
bans the use of the standard NOS common decks. Furthermore* 
the only flle.Hhich can be dealt with by reentrant code Is 
the editor workf lie. Terminal I/O will be funneled Into one 
module of eode» which shall conditionally compile to yield 
conventional FET-s and CIQ calls for FSE> and calls to the 
SMFEX Executive for SMF. 

i. The only *»r I teable storage which can be used other than 
local storage as described above shall reside in a single 
common blbck» or shall reside in based arrays whose pointer 
words iTB in the common block* The common block shall be 
organized Into several sections based on the various degrees 
of reentrancy services provided by the SMFEX Executive. in 
the single-tjser editor* portions of this common block must be 
complied to map exactly the same as the multi-user version* 
since that portion of the common block Is tranferred verbatim 
through . ttie workfile for communication between the two 
versions of the editor. All critical storage mapping must be 
identified as such In documentation. 

J. Reentrant code shall minimize dynamic relocation of based 
arrays. Relocation Is allowed if the pointer word Is treated 
as non-reentrant. Relocation is possible with limited 
reentrancy provided the pointer word is mapped into the 
reentrant section of the common block. Note that while this 
will keeo a pointer value alive for the duration of disk I/O* 
it is not able to keep any pointer valid aeross terminal I/O 
unless tiie pointer points within reentrant common Itself. 
This Is due to the re-mappIng of array locations performed by 
the SWFEX' Execut ive upon internal swaps. For those arrays 
re-»aoped by SflFEX swapping* no module except SMFEX can ever 
change tlie pointer word. 



